
\begin{chapter}{2APL Environments}
\label{chap:environment}

2APL agents can interact with environments in two ways: 1.
performing external actions which might yield a return-value (e.g.
sensing action), and 2. getting external events from the
environment. The agents can interact with all environments that
conform to the \emph{Environment Interface Standard}
(EIS)~\cite{EnvIntProMAS}, which can be downloaded from
\texttt{http://sourceforge.net/projects/apleis}. EIS is an
initiative for the easy exchange of environments between different
agent platforms. One can either use an environment that conforms to
the standard or implement its own one and ensure its conformity. To
that end please refer to the documents that accompany the
EIS-package.

The 2APL-package contains the \texttt{blockworld} environment
(see section~\ref{sec:externalaction}).
In the following, we explain
how to use the blockworld environment. In general, there are two kinds of
actions that an agent can perform with respect to the
environments: \emph{management actions} and \emph{domain actions}.


    The management actions are EIS-specific and thus generic to all kind of environments and are aimed
    at managing the agents-entities-relations, i.e., relating one 2APL agent with
    entities (for example their appearance) in the environments.
    EIS makes a strict distinction between agents (think: brains) and entities (think: bodies).
    An entity can be for example a robot that is controlled by an agent.
    In general entities provide agents with sensory and effectoric capabilities, agents can
    sense and act \emph{through} entities.
    EIS manages the
    so called \emph{agents-entities-relation}, which denotes which agent controls which
    entity. It is said that if an agent and an entity are \emph{associated} the agent controls the
    entity and thus has access to its sensors and effectors.
    In 2APL this agents-entities-relation is managed on the agents-level, that is the agents
    are to decide which entities they control.

    The syntax of the management actions
    actions is similar to external actions' one. The following are the
    management actions that an 2APL agent can perform with respect
    to an environment. For the blockworld environment, the term {\tt
    env} should be replaced by {\tt blockworld}.

        \begin{tabular}{ll}
      \textbf{action name:}
              & getFreeEntities \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{R} \\
      \textbf{example:}
              & \iapapl{@env( getFreeEntities() , R )} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                It returns a list R of all free unassociated
                entities in the environment env.} \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & getAllEntities \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{R} \\
      \textbf{example:}
              & \iapapl{@env( getAllEntities() , R )} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                It returns a list R of all entities in the environment env.} \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & associateWith \\
      \textbf{parameter(s):}
        & \iapapl{E} \\
      \textbf{return value(s):}
        & \iapapl{R} \\
      \textbf{example:}
              & \iapapl{@env( associateWith(E) , R )} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                It associates the action performing agent with the entity or a list of entities E.
                It returns a list R with the only element 'success'.} \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & disassociateFrom \\
      \textbf{parameter(s):}
        & \iapapl{E} \\
      \textbf{return value(s):}
        & \iapapl{R} \\
      \textbf{example:}
              & \iapapl{@env( disassociateFrom(E) , R )} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                It disassociates the action performing agent with the entity or a list of entities E.
                It returns a list R with the only element 'success'.} \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & getAllPercepts \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{R} \\
      \textbf{example:}
              & \iapapl{@env( getAllPercepts() , R )} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                It returns a list R of all current percepts.} \\
        \end{tabular}


  \begin{section}{Using the blockworld environment}
    \label{sec:blockworld}

        The {\tt blockworld} consists of a $n \times n$ world where agents
        can move in four directions (north, south, east and west). The world can
        contain bombs, stones, and dustbins. Agents can pickup and drop bombs. When a
        bomb is dropped in a dustbin, the bomb is destroyed. Figure
        \ref{fig:blockworld} shows an example instance of the {\tt blockworld} with
        one agent located in it. One can add and delete bombs, walls (stones), and
        dustbins. When a bomb is added within the sensing range of an agent a {\tt
        bombAt} event is sent to this agent. One can also select an agent by clicking the agent. When an
        agent is selected, the information about its actions and events is shown in
        the panel on the right. One can change some settings like the size of the
        world, and sensing range of the agent via the {\tt properties} menu. The
        world can be saved and loaded via the {\tt world} menu. An
        agent can perform the following actions in the {\tt blockworld}.

        \begin{figure}[ht]
          \centering{\epsfig{figure=images/blockworld.eps,width=.7\textwidth,angle=0}}
          \caption{An example instance of the blockworld with one agent located in
            it.}\label{fig:blockworld}
        \end{figure}


        \begin{tabular}{lll}
      \textbf{action name:}
              & enter & \\
      \textbf{parameter(s):}
        & \iapapl{X}    - X position & \\
        & \iapapl{Y}    - Y position & \\
        & \iapapl{C}    - A constant representing a color. & \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if :}
        & agent has already entered & \\
        & the position is outside the world & \\
        & the position is occupied by another agent & \\
      \textbf{example:}
              & \iapapl{@blockworld( enter(5,5,red), R)} & \\
            \textbf{description:} &  & \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to inserts an agent in the {\tt blockworld} at a given position (X, Y).
                The options for the color are: army,
                blue,   gray,   green, orange, pink, purple, red (the color which will also
                be selected for invalid constants), teal, and yellow.
            } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & sensePosition \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[X,Y]} \\
      \textbf{example:}
              & \iapapl{@blockworld( sensePosition(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Senses the position of the agent within the {\tt blockworld}. If the agent is
                not in the {\tt blockworld} there will be no substitution for the return
                value, otherwise it will be the coordinates of the agent at \iapapl{[X,Y]}. } \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & north &\\
      \textbf{parameter(s):}
        & none &\\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the position is outside the world &\\
        & the position is occupied by another agent &\\
      \textbf{example:}
              & \iapapl{@blockworld( north(), R)} &\\
            \textbf{description:} & \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to move the agent through the {\tt blockworld} to the position above
                $(Y-1)$ the current position.} \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & south \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the position is outside the world &\\
        & the position is occupied by another agent &\\
      \textbf{example:}
              & \iapapl{@blockworld( south(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to move the agent through the {\tt blockworld} to the position above
                $(Y+1)$ the current position. } \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & east \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the position is outside the world &\\
        & the position is occupied by another agent &\\
      \textbf{example:}
              & \iapapl{@blockworld( east(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to move the agent through the {\tt blockworld} to the position above
                $(X+1)$ the current position. } \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & west \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the position is outside the world &\\
        & the position is occupied by another agent &\\
      \textbf{example:}
              & \iapapl{@blockworld( west(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to move the agent through the {\tt blockworld} to the position above
                $(X-1)$ the current position.} \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseBombs \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        &  \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseBombs(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all bombs in the sense range. The first element of the
                sublist (each bomb description) is always 'default', the second is the X
                position and the third the Y position. } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseAllBombs \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        &  \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseAllBombs(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all bombs, also the ones outside the sense range. The
                first element of the sublist (each bomb description) is always
                'default', the second is the X position and the third the Y position. }
                \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & pickup \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the agent already carries a bomb &\\
        & there is no bomb to pickup &\\
      \textbf{example:}
              & \iapapl{@blockworld( pickup(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Tries to pickup a bomb. } \\
        \end{tabular}

        \begin{tabular}{lll}
      \textbf{action name:}
              & drop \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):} & none & \\
        \textbf{fails if:}
        & the agent doesn't carry a bomb &\\
        & there is already a bomb in the position &\\
      \multicolumn{2}{p{14.3cm}}{
                The agent tries to drop the bomb it carries.  } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseAgent \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[A1, X1, Y1], [A2, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseAgent(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all agents in the sense range. The first element of the
                sublist (each agent description) is the name (A) of the agent, the
                second is the X position and the third the Y position.  } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseAllAgent \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[A1, X1, Y1], [A2, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseAllAgent(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all the agents independent of the sense range.  } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseStones \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseStones(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all stones in the sense range. The first element of the
                sublist (each stone description) is always 'default', the second is the
                X position and the third the Y position. } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseAllStones \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseAllStones(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all stones, also the ones outside the sense range. The
                first element of the sublist (each stone description) is always
                'default', the second is the X position and the third the Y position. }
                \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseTraps \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseTraps(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all dustbins in the sense range. The first element of the
                sublist (each dustbin description) is always 'default', the second is the X
                position and the third the Y position.  } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & senseAllTraps \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[[default, X1, Y1], [default, X2, Y2], ...]} \\
      \textbf{example:}
              & \iapapl{@blockworld( senseAllTraps(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Gives a list of all dustbins, also the ones outside the sense range. The
                first element of the sublist (each dustbin description) is always
                'default', the second is the X position and the third the Y position.   }
                \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & getSenseRange \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[SenseRange]} \\
      \textbf{example:}
              & \iapapl{@blockworld( getSenseRange(),R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
              Returns the sense-range of the agent.
            } \\
        \end{tabular}

        \begin{tabular}{ll}
      \textbf{action name:}
              & getWorldSize \\
      \textbf{parameter(s):}
        & none \\
      \textbf{return value(s):}
        & \iapapl{[Width, Height]} \\
      \textbf{example:}
              & \iapapl{@blockworld( getWorldSize(), R)} \\
            \textbf{description:} &  \\
      \multicolumn{2}{p{14.3cm}}{
                Returns the size of the {\tt blockworld}, the first parameter is the width and
                the second the height.  } \\
        \end{tabular}

    \end{section}



\end{chapter}
